Inside Macintosh: QuickTime /

Chapter 2 - Movie Toolbox / Movie Toolbox Reference

Functions for Editing Movies / Adding Samples to Media Structures

AddMediaSampleReference

The AddMediaSampleReference function allows your application to work with samples that have already been added to a movie data file. Instead of actually writing out samples to disk, this function writes out references to existing samples, which you specify in the dataOffset and size parameters.

pascal OSErr AddMediaSampleReference (Media theMedia, 
                     long dataOffset,
                     unsigned long size, 
                     TimeValue durationPerSample,
                     SampleDescriptionHandle sampleDescriptionH, 
                     long numberOfSamples, short sampleFlags, 
                     TimeValue *sampleTime);

theMedia

Specifies the media for this operation. Your application obtains this media identifier from such Movie Toolbox functions as NewTrackMedia and GetTrackMedia (described on page 2-138 and page 2-190, respectively).

dataOffset

Specifies the offset into the movie data file. This parameter is used differently by each data handler. For example, for the standard HFS data handler, this parameter specifies the offset into the file. This parameter contains either data you add yourself or the data offset returned by the GetMediaSampleReference function (described on page 2-262).

size

Specifies the number of bytes of sample data to be identified by the reference. This parameter indicates the total number of bytes in the sample data, not the number of bytes per sample. Use the numberOfSamples parameter to indicate the number of samples that are contained in the reference.

durationPerSample

Specifies the duration of each sample in the reference. You must specify this parameter in the media's time scale. For example, if you are referring to sound that was sampled at 22 kHz in a media that contains a sound track with the same time scale, to add a reference to a single sample you would set the durationPerSample parameter to 1. Similarly, if you are referring to video that was recorded at 10 frames per second in a video media that has a time scale of 60, you would set this parameter to 6 to add a reference to a single sample.

sampleDescriptionH

Contains a handle to a sample description. Some media structures may require sample descriptions. There are different sample descriptions for different types of samples. For example, a media that contains compressed video requires that you supply an image description (see the chapter "Image Compression Manager" in this book for more information about image description structures). A media that contains sound requires that you supply a sound description structure (see "The Sound Description Structure" on page 2-68 for more information about
sound description structures).

If the media does not require a sample description, set this
parameter to nil.

numberOfSamples

Specifies the number of samples contained in the reference. For details, see the AddMediaSample function description beginning on page 2-256.

sampleFlags

Contains flags that control the operation. The following flag is available (set unused flags to 0):

mediaSampleNotSync

Indicates that the sample to be added is not a sync sample. Set this flag to 1 if the sample is not a sync sample. Set this flag to 0 if the sample is a sync sample.

sampleTime

Contains a pointer to a time value. After adding the reference to the media, the AddMediaSampleReference function returns the time where the reference was inserted in the time value referred to by
this parameter. If you do not want to receive this information, set this parameter to nil.

DESCRIPTION

The AddMediaSampleReference function does not add sample data to the file or device that contains a media. Rather, it defines references to sample data that you previously added to a movie data file. As with the AddMediaSample function (described in the previous section), your application specifies the media for the operation. Note that one reference may refer to more than one sample--all the samples described by a reference must be the same size. This function does not update the movie data file as part of the add operation. Therefore, your application does not have to call the BeginMediaEdits function (described on page 2-255) before calling AddMediaSampleReference.

ERROR CODES

invalidMedia

-2008

This media is corrupted or invalid

Memory Manager errors

SEE ALSO

If you want to add new samples to a media data file, use the AddMediaSample function, which is described in the previous section.